-
Notifications
You must be signed in to change notification settings - Fork 89
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Add support for CLI tab completions #741
base: main
Are you sure you want to change the base?
Conversation
Most shells provide path completions by default. However, when using custom shell completions, this default behavior is overridden. To specify that an argument should use path completions, you need to use For example: parser.add_argument(
"input_dir",
type=Path,
help="Checkpoint directory",
).complete = shtab.DIRECTORY # type: ignore[attr-defined] parser.add_argument(
"--config-file",
dest="config_files",
metavar="CONFIG_FILE",
type=Path,
nargs="*",
help="YAML configuration file(s)",
).complete = shtab.FILE # type: ignore[attr-defined] This configuration ensures that I also had to ignore the type hints as I can't seem to find a better way to handle them. |
Neat! Happy to merge this once ready. Any reason why it is draft at the moment? |
I was waiting for further instructions on how to address the post-install issue. If we are not going to handle the shell completions setup automatically (i.e. post install code). Should I update some docs like INSTALL_FROM_SOURCE.md with instructions on how to setup and enable shell completions? |
Should I add support for PowerShell and fish shell (if possible)? Currently supported shells are bash, zsh and tcsh. Which supports almost all Linux systems and macos |
Considering that our CLI commands are populated dynamically during runtime based on the packages installed in the Python environment, the safest would be to let users manually update their bashrc/zhrc once they have their environment fully set up. So adding some brief instructions in README (right after "Installing from Source") makes sense to me.
I don't think they are necessary. PowerShell is mainly used on Windows. I haven't seen anyone using it on Linux/macOS. As long as we support bash and zsh, the rest is not really much relevant nowadays. |
…nto cli/tab-completion
…rseq2 into cli/tab-completion
I have added a section in the Readme file on setting up shell completions in 4af2be4. This PR should be ready for merging now. |
What does this PR do? Please describe:
This PR extends the CLI with support for tab completions. Initially, I tried using argcomplete, but it was slow and ran a Fairseq2 process each time I pressed tab, which was far from ideal.
I then discovered shtab, a package that generates shell tab completion scripts efficiently. According to its README:
After implementing
shtab
, tab completion works beautifully. Here are some examples:It’s especially useful for things like presets. Instead of listing presets and copying them manually, you can now use tab completion:
It also works with arguments:
Tab completions are specific to each shell and require the installation of corresponding scripts in the shell's directory.
Initially, I intended to extend the project by adding post-install scripts to automatically set up tab completion scripts (b63af98). However, I discovered that this approach only worked with zip and tarball distributions, while fairseq2 uses wheel builds. As a result, I reverted that change.
Currently, you can enable tab completions manually by using
--print-completions {bash|zsh|tcsh}
. The output of this command can be saved to the shell's completion scripts directory for persistence or evaluated directly for the current session.For example:
Please note: each time the CLI interfaces are modified, the shell completion scripts need to be updated.
Does your PR introduce any breaking changes? If yes, please list them:
None.
Check list: